///////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2009 Summit Contributors.  
// See: http://code.google.com/p/tyemill/wiki/SummitContributors
//
// The name and logo of Summit are trademarks of TYEMILL, LLC - All Rights 
// Reserved.
//
// Permission is hereby granted, free of charge, to any person obtaining a 
// copy of this software and associated documentation files (the "Software"), 
// to deal in the Software without restriction, including without 
// limitation the rights to use, copy, modify, merge, publish, distribute, 
// sublicense, and/or sell copies of the Software, and to permit persons to 
// whom the Software is furnished to do so, subject to the following 
// conditions:
//
// The above copyright notice and this permission notice shall be included 
// in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
// DEALINGS IN THE SOFTWARE.
///////////////////////////////////////////////////////////////////////////////

package summit.basecamp.helpers
{
	
import flash.net.URLRequestMethod;

import summit.basecamp.constants.BasecampOperation;
import summit.basecamp.constants.BasecampResource;
import summit.net.BasecampRequest;
import org.tyemill.utils.Assert;

/**
 * Helpers for Basecamp person operations.
 */
public class PersonHelper
{
	/** @private constant **/
	private static const TYPE:String = BasecampResource.PERSON;
	
	/** @private **/
	public function PersonHelper()
	{
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for reading a single person.
	 * 
	 * <p>Providing a <code>null</code> <code>id</code> will return a record
	 * for the requesting user, represented by the <code>AccountToken</code>
	 * passed to the loader.</p> 
	 * 
	 * @param id The id of the person to be read.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */	
	public static function read(id:String):BasecampRequest
	{
		// GET /me.xml
		// GET /people/#{person_id}.xml
		var path:String;
		
		if(!id || "" == id) path = "/me.xml"; 
		else path = "/contacts/person/" + id;
		
		return new BasecampRequest(path, URLRequestMethod.GET, TYPE, 
		BasecampOperation.READ);
	}
	
	/**
	 * Builds a <code>BasecampRequest</code> for reading a list of people.
	 * 
	 * <p>Providing only a <code>companyId</code> will result in a list 
	 * containing all people across all projects associated with the specified 
	 * company.</p>
	 * 
	 * <p>Providing both a <code>companyId</code> and a <code>projectId</code>
	 * will result in a list containing all people associated with the 
	 * specified project.</p>
	 *
	 * <p>Providing only a <code>projectId</code> will result in a list 
	 * containing all people with access to the specified project.</p>
	 *  
	 * <p>In all cases, the created list contains only people that are visible
	 * to the requesting user.</p>
	 * 
	 * <p>Providing <code>null</code> for both arguments will list all people
	 * visible to (and including) the requesting user.</p>
	 * 
	 * @param companyId The id of a company. 
	 * @param projectId The id of a project.
	 * 
	 * @return A request ready for use with <code>BasecampLoader.load</code>.
	 */
	public static function list(companyId:String, 
	projectId:String = null):BasecampRequest
	{
		var path:String;
	
		// GET /people.xml
		// GET /contacts/people/#{company_id}
		// GET /projects/#{project_id}/people.xml
		// GET /projects/#{project_id}/contacts/people/#{company_id}
		if(null == companyId && null == projectId) path = "/people.xml";
		else if(null == projectId) path = "/contacts/people/" + companyId;
		else if(null == companyId) 
			path = "/projects/" + projectId + "/people.xml"; 
		else path = "/projects/" + projectId + "/contacts/people/" + companyId;
		
		return new BasecampRequest(path, URLRequestMethod.GET, TYPE, 
		BasecampOperation.LIST); 
	}
	
}
}
//////////////////////////////////////////////////////// gmarius@tyemill.com //